home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / uwb.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  23.5 KB  |  766 lines
  1. /*
  2.  * Ultra Wide Band
  3.  * UWB API
  4.  *
  5.  * Copyright (C) 2005-2006 Intel Corporation
  6.  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
  7.  *
  8.  * This program is free software; you can redistribute it and/or
  9.  * modify it under the terms of the GNU General Public License version
  10.  * 2 as published by the Free Software Foundation.
  11.  *
  12.  * This program is distributed in the hope that it will be useful,
  13.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15.  * GNU General Public License for more details.
  16.  *
  17.  * You should have received a copy of the GNU General Public License
  18.  * along with this program; if not, write to the Free Software
  19.  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20.  * 02110-1301, USA.
  21.  *
  22.  *
  23.  * FIXME: doc: overview of the API, different parts and pointers
  24.  */
  25.  
  26. #ifndef __LINUX__UWB_H__
  27. #define __LINUX__UWB_H__
  28.  
  29. #include <linux/limits.h>
  30. #include <linux/device.h>
  31. #include <linux/mutex.h>
  32. #include <linux/timer.h>
  33. #include <linux/workqueue.h>
  34. #include <linux/uwb/spec.h>
  35.  
  36. struct uwb_dev;
  37. struct uwb_beca_e;
  38. struct uwb_rc;
  39. struct uwb_rsv;
  40. struct uwb_dbg;
  41.  
  42. /**
  43.  * struct uwb_dev - a UWB Device
  44.  * @rc: UWB Radio Controller that discovered the device (kind of its
  45.  *     parent).
  46.  * @bce: a beacon cache entry for this device; or NULL if the device
  47.  *     is a local radio controller.
  48.  * @mac_addr: the EUI-48 address of this device.
  49.  * @dev_addr: the current DevAddr used by this device.
  50.  * @beacon_slot: the slot number the beacon is using.
  51.  * @streams: bitmap of streams allocated to reservations targeted at
  52.  *     this device.  For an RC, this is the streams allocated for
  53.  *     reservations targeted at DevAddrs.
  54.  *
  55.  * A UWB device may either by a neighbor or part of a local radio
  56.  * controller.
  57.  */
  58. struct uwb_dev {
  59.     struct mutex mutex;
  60.     struct list_head list_node;
  61.     struct device dev;
  62.     struct uwb_rc *rc;        /* radio controller */
  63.     struct uwb_beca_e *bce;        /* Beacon Cache Entry */
  64.  
  65.     struct uwb_mac_addr mac_addr;
  66.     struct uwb_dev_addr dev_addr;
  67.     int beacon_slot;
  68.     DECLARE_BITMAP(streams, UWB_NUM_STREAMS);
  69. };
  70. #define to_uwb_dev(d) container_of(d, struct uwb_dev, dev)
  71.  
  72. /**
  73.  * UWB HWA/WHCI Radio Control {Command|Event} Block context IDs
  74.  *
  75.  * RC[CE]Bs have a 'context ID' field that matches the command with
  76.  * the event received to confirm it.
  77.  *
  78.  * Maximum number of context IDs
  79.  */
  80. enum { UWB_RC_CTX_MAX = 256 };
  81.  
  82.  
  83. /** Notification chain head for UWB generated events to listeners */
  84. struct uwb_notifs_chain {
  85.     struct list_head list;
  86.     struct mutex mutex;
  87. };
  88.  
  89. /**
  90.  * struct uwb_mas_bm - a bitmap of all MAS in a superframe
  91.  * @bm: a bitmap of length #UWB_NUM_MAS
  92.  */
  93. struct uwb_mas_bm {
  94.     DECLARE_BITMAP(bm, UWB_NUM_MAS);
  95. };
  96.  
  97. /**
  98.  * uwb_rsv_state - UWB Reservation state.
  99.  *
  100.  * NONE - reservation is not active (no DRP IE being transmitted).
  101.  *
  102.  * Owner reservation states:
  103.  *
  104.  * INITIATED - owner has sent an initial DRP request.
  105.  * PENDING - target responded with pending Reason Code.
  106.  * MODIFIED - reservation manager is modifying an established
  107.  * reservation with a different MAS allocation.
  108.  * ESTABLISHED - the reservation has been successfully negotiated.
  109.  *
  110.  * Target reservation states:
  111.  *
  112.  * DENIED - request is denied.
  113.  * ACCEPTED - request is accepted.
  114.  * PENDING - PAL has yet to make a decision to whether to accept or
  115.  * deny.
  116.  *
  117.  * FIXME: further target states TBD.
  118.  */
  119. enum uwb_rsv_state {
  120.     UWB_RSV_STATE_NONE,
  121.     UWB_RSV_STATE_O_INITIATED,
  122.     UWB_RSV_STATE_O_PENDING,
  123.     UWB_RSV_STATE_O_MODIFIED,
  124.     UWB_RSV_STATE_O_ESTABLISHED,
  125.     UWB_RSV_STATE_T_ACCEPTED,
  126.     UWB_RSV_STATE_T_DENIED,
  127.     UWB_RSV_STATE_T_PENDING,
  128.  
  129.     UWB_RSV_STATE_LAST,
  130. };
  131.  
  132. enum uwb_rsv_target_type {
  133.     UWB_RSV_TARGET_DEV,
  134.     UWB_RSV_TARGET_DEVADDR,
  135. };
  136.  
  137. /**
  138.  * struct uwb_rsv_target - the target of a reservation.
  139.  *
  140.  * Reservations unicast and targeted at a single device
  141.  * (UWB_RSV_TARGET_DEV); or (e.g., in the case of WUSB) targeted at a
  142.  * specific (private) DevAddr (UWB_RSV_TARGET_DEVADDR).
  143.  */
  144. struct uwb_rsv_target {
  145.     enum uwb_rsv_target_type type;
  146.     union {
  147.         struct uwb_dev *dev;
  148.         struct uwb_dev_addr devaddr;
  149.     };
  150. };
  151.  
  152. /*
  153.  * Number of streams reserved for reservations targeted at DevAddrs.
  154.  */
  155. #define UWB_NUM_GLOBAL_STREAMS 1
  156.  
  157. typedef void (*uwb_rsv_cb_f)(struct uwb_rsv *rsv);
  158.  
  159. /**
  160.  * struct uwb_rsv - a DRP reservation
  161.  *
  162.  * Data structure management:
  163.  *
  164.  * @rc:             the radio controller this reservation is for
  165.  *                  (as target or owner)
  166.  * @rc_node:        a list node for the RC
  167.  * @pal_node:       a list node for the PAL
  168.  *
  169.  * Owner and target parameters:
  170.  *
  171.  * @owner:          the UWB device owning this reservation
  172.  * @target:         the target UWB device
  173.  * @type:           reservation type
  174.  *
  175.  * Owner parameters:
  176.  *
  177.  * @max_mas:        maxiumum number of MAS
  178.  * @min_mas:        minimum number of MAS
  179.  * @sparsity:       owner selected sparsity
  180.  * @is_multicast:   true iff multicast
  181.  *
  182.  * @callback:       callback function when the reservation completes
  183.  * @pal_priv:       private data for the PAL making the reservation
  184.  *
  185.  * Reservation status:
  186.  *
  187.  * @status:         negotiation status
  188.  * @stream:         stream index allocated for this reservation
  189.  * @mas:            reserved MAS
  190.  * @drp_ie:         the DRP IE
  191.  * @ie_valid:       true iff the DRP IE matches the reservation parameters
  192.  *
  193.  * DRP reservations are uniquely identified by the owner, target and
  194.  * stream index.  However, when using a DevAddr as a target (e.g., for
  195.  * a WUSB cluster reservation) the responses may be received from
  196.  * devices with different DevAddrs.  In this case, reservations are
  197.  * uniquely identified by just the stream index.  A number of stream
  198.  * indexes (UWB_NUM_GLOBAL_STREAMS) are reserved for this.
  199.  */
  200. struct uwb_rsv {
  201.     struct uwb_rc *rc;
  202.     struct list_head rc_node;
  203.     struct list_head pal_node;
  204.  
  205.     struct uwb_dev *owner;
  206.     struct uwb_rsv_target target;
  207.     enum uwb_drp_type type;
  208.     int max_mas;
  209.     int min_mas;
  210.     int sparsity;
  211.     bool is_multicast;
  212.  
  213.     uwb_rsv_cb_f callback;
  214.     void *pal_priv;
  215.  
  216.     enum uwb_rsv_state state;
  217.     u8 stream;
  218.     struct uwb_mas_bm mas;
  219.     struct uwb_ie_drp *drp_ie;
  220.     bool ie_valid;
  221.     struct timer_list timer;
  222.     bool expired;
  223. };
  224.  
  225. static const
  226. struct uwb_mas_bm uwb_mas_bm_zero = { .bm = { 0 } };
  227.  
  228. static inline void uwb_mas_bm_copy_le(void *dst, const struct uwb_mas_bm *mas)
  229. {
  230.     bitmap_copy_le(dst, mas->bm, UWB_NUM_MAS);
  231. }
  232.  
  233. /**
  234.  * struct uwb_drp_avail - a radio controller's view of MAS usage
  235.  * @global:   MAS unused by neighbors (excluding reservations targetted
  236.  *            or owned by the local radio controller) or the beaon period
  237.  * @local:    MAS unused by local established reservations
  238.  * @pending:  MAS unused by local pending reservations
  239.  * @ie:       DRP Availability IE to be included in the beacon
  240.  * @ie_valid: true iff @ie is valid and does not need to regenerated from
  241.  *            @global and @local
  242.  *
  243.  * Each radio controller maintains a view of MAS usage or
  244.  * availability. MAS available for a new reservation are determined
  245.  * from the intersection of @global, @local, and @pending.
  246.  *
  247.  * The radio controller must transmit a DRP Availability IE that's the
  248.  * intersection of @global and @local.
  249.  *
  250.  * A set bit indicates the MAS is unused and available.
  251.  *
  252.  * rc->rsvs_mutex should be held before accessing this data structure.
  253.  *
  254.  * [ECMA-368] section 17.4.3.
  255.  */
  256. struct uwb_drp_avail {
  257.     DECLARE_BITMAP(global, UWB_NUM_MAS);
  258.     DECLARE_BITMAP(local, UWB_NUM_MAS);
  259.     DECLARE_BITMAP(pending, UWB_NUM_MAS);
  260.     struct uwb_ie_drp_avail ie;
  261.     bool ie_valid;
  262. };
  263.  
  264.  
  265. const char *uwb_rsv_state_str(enum uwb_rsv_state state);
  266. const char *uwb_rsv_type_str(enum uwb_drp_type type);
  267.  
  268. struct uwb_rsv *uwb_rsv_create(struct uwb_rc *rc, uwb_rsv_cb_f cb,
  269.                    void *pal_priv);
  270. void uwb_rsv_destroy(struct uwb_rsv *rsv);
  271.  
  272. int uwb_rsv_establish(struct uwb_rsv *rsv);
  273. int uwb_rsv_modify(struct uwb_rsv *rsv,
  274.            int max_mas, int min_mas, int sparsity);
  275. void uwb_rsv_terminate(struct uwb_rsv *rsv);
  276.  
  277. void uwb_rsv_accept(struct uwb_rsv *rsv, uwb_rsv_cb_f cb, void *pal_priv);
  278.  
  279. /**
  280.  * Radio Control Interface instance
  281.  *
  282.  *
  283.  * Life cycle rules: those of the UWB Device.
  284.  *
  285.  * @index:    an index number for this radio controller, as used in the
  286.  *            device name.
  287.  * @version:  version of protocol supported by this device
  288.  * @priv:     Backend implementation; rw with uwb_dev.dev.sem taken.
  289.  * @cmd:      Backend implementation to execute commands; rw and call
  290.  *            only  with uwb_dev.dev.sem taken.
  291.  * @reset:    Hardware reset of radio controller and any PAL controllers.
  292.  * @filter:   Backend implementation to manipulate data to and from device
  293.  *            to be compliant to specification assumed by driver (WHCI
  294.  *            0.95).
  295.  *
  296.  *            uwb_dev.dev.mutex is used to execute commands and update
  297.  *            the corresponding structures; can't use a spinlock
  298.  *            because rc->cmd() can sleep.
  299.  * @ies:         This is a dynamically allocated array cacheing the
  300.  *               IEs (settable by the host) that the beacon of this
  301.  *               radio controller is currently sending.
  302.  *
  303.  *               In reality, we store here the full command we set to
  304.  *               the radio controller (which is basically a command
  305.  *               prefix followed by all the IEs the beacon currently
  306.  *               contains). This way we don't have to realloc and
  307.  *               memcpy when setting it.
  308.  *
  309.  *               We set this up in uwb_rc_ie_setup(), where we alloc
  310.  *               this struct, call get_ie() [so we know which IEs are
  311.  *               currently being sent, if any].
  312.  *
  313.  * @ies_capacity:Amount of space (in bytes) allocated in @ies. The
  314.  *               amount used is given by sizeof(*ies) plus ies->wIELength
  315.  *               (which is a little endian quantity all the time).
  316.  * @ies_mutex:   protect the IE cache
  317.  * @dbg:         information for the debug interface
  318.  */
  319. struct uwb_rc {
  320.     struct uwb_dev uwb_dev;
  321.     int index;
  322.     u16 version;
  323.  
  324.     struct module *owner;
  325.     void *priv;
  326.     int (*start)(struct uwb_rc *rc);
  327.     void (*stop)(struct uwb_rc *rc);
  328.     int (*cmd)(struct uwb_rc *, const struct uwb_rccb *, size_t);
  329.     int (*reset)(struct uwb_rc *rc);
  330.     int (*filter_cmd)(struct uwb_rc *, struct uwb_rccb **, size_t *);
  331.     int (*filter_event)(struct uwb_rc *, struct uwb_rceb **, const size_t,
  332.                 size_t *, size_t *);
  333.  
  334.     spinlock_t neh_lock;        /* protects neh_* and ctx_* */
  335.     struct list_head neh_list;    /* Open NE handles */
  336.     unsigned long ctx_bm[UWB_RC_CTX_MAX / 8 / sizeof(unsigned long)];
  337.     u8 ctx_roll;
  338.  
  339.     int beaconing;            /* Beaconing state [channel number] */
  340.     int scanning;
  341.     enum uwb_scan_type scan_type:3;
  342.     unsigned ready:1;
  343.     struct uwb_notifs_chain notifs_chain;
  344.  
  345.     struct uwb_drp_avail drp_avail;
  346.     struct list_head reservations;
  347.     struct mutex rsvs_mutex;
  348.     struct workqueue_struct *rsv_workq;
  349.     struct work_struct rsv_update_work;
  350.  
  351.     struct mutex ies_mutex;
  352.     struct uwb_rc_cmd_set_ie *ies;
  353.     size_t ies_capacity;
  354.  
  355.     spinlock_t pal_lock;
  356.     struct list_head pals;
  357.  
  358.     struct uwb_dbg *dbg;
  359. };
  360.  
  361.  
  362. /**
  363.  * struct uwb_pal - a UWB PAL
  364.  * @name:    descriptive name for this PAL (wushc, wlp, etc.).
  365.  * @device:  a device for the PAL.  Used to link the PAL and the radio
  366.  *           controller in sysfs.
  367.  * @new_rsv: called when a peer requests a reservation (may be NULL if
  368.  *           the PAL cannot accept reservation requests).
  369.  *
  370.  * A Protocol Adaptation Layer (PAL) is a user of the WiMedia UWB
  371.  * radio platform (e.g., WUSB, WLP or Bluetooth UWB AMP).
  372.  *
  373.  * The PALs using a radio controller must register themselves to
  374.  * permit the UWB stack to coordinate usage of the radio between the
  375.  * various PALs or to allow PALs to response to certain requests from
  376.  * peers.
  377.  *
  378.  * A struct uwb_pal should be embedded in a containing structure
  379.  * belonging to the PAL and initialized with uwb_pal_init()).  Fields
  380.  * should be set appropriately by the PAL before registering the PAL
  381.  * with uwb_pal_register().
  382.  */
  383. struct uwb_pal {
  384.     struct list_head node;
  385.     const char *name;
  386.     struct device *device;
  387.     void (*new_rsv)(struct uwb_rsv *rsv);
  388. };
  389.  
  390. void uwb_pal_init(struct uwb_pal *pal);
  391. int uwb_pal_register(struct uwb_rc *rc, struct uwb_pal *pal);
  392. void uwb_pal_unregister(struct uwb_rc *rc, struct uwb_pal *pal);
  393.  
  394. /*
  395.  * General public API
  396.  *
  397.  * This API can be used by UWB device drivers or by those implementing
  398.  * UWB Radio Controllers
  399.  */
  400. struct uwb_dev *uwb_dev_get_by_devaddr(struct uwb_rc *rc,
  401.                        const struct uwb_dev_addr *devaddr);
  402. struct uwb_dev *uwb_dev_get_by_rc(struct uwb_dev *, struct uwb_rc *);
  403. static inline void uwb_dev_get(struct uwb_dev *uwb_dev)
  404. {
  405.     get_device(&uwb_dev->dev);
  406. }
  407. static inline void uwb_dev_put(struct uwb_dev *uwb_dev)
  408. {
  409.     put_device(&uwb_dev->dev);
  410. }
  411. struct uwb_dev *uwb_dev_try_get(struct uwb_rc *rc, struct uwb_dev *uwb_dev);
  412.  
  413. /**
  414.  * Callback function for 'uwb_{dev,rc}_foreach()'.
  415.  *
  416.  * @dev:  Linux device instance
  417.  *        'uwb_dev = container_of(dev, struct uwb_dev, dev)'
  418.  * @priv: Data passed by the caller to 'uwb_{dev,rc}_foreach()'.
  419.  *
  420.  * @returns: 0 to continue the iterations, any other val to stop
  421.  *           iterating and return the value to the caller of
  422.  *           _foreach().
  423.  */
  424. typedef int (*uwb_dev_for_each_f)(struct device *dev, void *priv);
  425. int uwb_dev_for_each(struct uwb_rc *rc, uwb_dev_for_each_f func, void *priv);
  426.  
  427. struct uwb_rc *uwb_rc_alloc(void);
  428. struct uwb_rc *uwb_rc_get_by_dev(const struct uwb_dev_addr *);
  429. struct uwb_rc *uwb_rc_get_by_grandpa(const struct device *);
  430. void uwb_rc_put(struct uwb_rc *rc);
  431.  
  432. typedef void (*uwb_rc_cmd_cb_f)(struct uwb_rc *rc, void *arg,
  433.                                 struct uwb_rceb *reply, ssize_t reply_size);
  434.  
  435. int uwb_rc_cmd_async(struct uwb_rc *rc, const char *cmd_name,
  436.              struct uwb_rccb *cmd, size_t cmd_size,
  437.              u8 expected_type, u16 expected_event,
  438.              uwb_rc_cmd_cb_f cb, void *arg);
  439. ssize_t uwb_rc_cmd(struct uwb_rc *rc, const char *cmd_name,
  440.            struct uwb_rccb *cmd, size_t cmd_size,
  441.            struct uwb_rceb *reply, size_t reply_size);
  442. ssize_t uwb_rc_vcmd(struct uwb_rc *rc, const char *cmd_name,
  443.             struct uwb_rccb *cmd, size_t cmd_size,
  444.             u8 expected_type, u16 expected_event,
  445.             struct uwb_rceb **preply);
  446. ssize_t uwb_rc_get_ie(struct uwb_rc *, struct uwb_rc_evt_get_ie **);
  447. int uwb_bg_joined(struct uwb_rc *rc);
  448.  
  449. size_t __uwb_addr_print(char *, size_t, const unsigned char *, int);
  450.  
  451. int uwb_rc_dev_addr_set(struct uwb_rc *, const struct uwb_dev_addr *);
  452. int uwb_rc_dev_addr_get(struct uwb_rc *, struct uwb_dev_addr *);
  453. int uwb_rc_mac_addr_set(struct uwb_rc *, const struct uwb_mac_addr *);
  454. int uwb_rc_mac_addr_get(struct uwb_rc *, struct uwb_mac_addr *);
  455. int __uwb_mac_addr_assigned_check(struct device *, void *);
  456. int __uwb_dev_addr_assigned_check(struct device *, void *);
  457.  
  458. /* Print in @buf a pretty repr of @addr */
  459. static inline size_t uwb_dev_addr_print(char *buf, size_t buf_size,
  460.                     const struct uwb_dev_addr *addr)
  461. {
  462.     return __uwb_addr_print(buf, buf_size, addr->data, 0);
  463. }
  464.  
  465. /* Print in @buf a pretty repr of @addr */
  466. static inline size_t uwb_mac_addr_print(char *buf, size_t buf_size,
  467.                     const struct uwb_mac_addr *addr)
  468. {
  469.     return __uwb_addr_print(buf, buf_size, addr->data, 1);
  470. }
  471.  
  472. /* @returns 0 if device addresses @addr2 and @addr1 are equal */
  473. static inline int uwb_dev_addr_cmp(const struct uwb_dev_addr *addr1,
  474.                    const struct uwb_dev_addr *addr2)
  475. {
  476.     return memcmp(addr1, addr2, sizeof(*addr1));
  477. }
  478.  
  479. /* @returns 0 if MAC addresses @addr2 and @addr1 are equal */
  480. static inline int uwb_mac_addr_cmp(const struct uwb_mac_addr *addr1,
  481.                    const struct uwb_mac_addr *addr2)
  482. {
  483.     return memcmp(addr1, addr2, sizeof(*addr1));
  484. }
  485.  
  486. /* @returns !0 if a MAC @addr is a broadcast address */
  487. static inline int uwb_mac_addr_bcast(const struct uwb_mac_addr *addr)
  488. {
  489.     struct uwb_mac_addr bcast = {
  490.         .data = { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff }
  491.     };
  492.     return !uwb_mac_addr_cmp(addr, &bcast);
  493. }
  494.  
  495. /* @returns !0 if a MAC @addr is all zeroes*/
  496. static inline int uwb_mac_addr_unset(const struct uwb_mac_addr *addr)
  497. {
  498.     struct uwb_mac_addr unset = {
  499.         .data = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
  500.     };
  501.     return !uwb_mac_addr_cmp(addr, &unset);
  502. }
  503.  
  504. /* @returns !0 if the address is in use. */
  505. static inline unsigned __uwb_dev_addr_assigned(struct uwb_rc *rc,
  506.                            struct uwb_dev_addr *addr)
  507. {
  508.     return uwb_dev_for_each(rc, __uwb_dev_addr_assigned_check, addr);
  509. }
  510.  
  511. /*
  512.  * UWB Radio Controller API
  513.  *
  514.  * This API is used (in addition to the general API) to implement UWB
  515.  * Radio Controllers.
  516.  */
  517. void uwb_rc_init(struct uwb_rc *);
  518. int uwb_rc_add(struct uwb_rc *, struct device *dev, void *rc_priv);
  519. void uwb_rc_rm(struct uwb_rc *);
  520. void uwb_rc_neh_grok(struct uwb_rc *, void *, size_t);
  521. void uwb_rc_neh_error(struct uwb_rc *, int);
  522. void uwb_rc_reset_all(struct uwb_rc *rc);
  523.  
  524. /**
  525.  * uwb_rsv_is_owner - is the owner of this reservation the RC?
  526.  * @rsv: the reservation
  527.  */
  528. static inline bool uwb_rsv_is_owner(struct uwb_rsv *rsv)
  529. {
  530.     return rsv->owner == &rsv->rc->uwb_dev;
  531. }
  532.  
  533. /**
  534.  * Events generated by UWB that can be passed to any listeners
  535.  *
  536.  * Higher layers can register callback functions with the radio
  537.  * controller using uwb_notifs_register(). The radio controller
  538.  * maintains a list of all registered handlers and will notify all
  539.  * nodes when an event occurs.
  540.  */
  541. enum uwb_notifs {
  542.     UWB_NOTIF_BG_JOIN = 0,    /* radio controller joined a beacon group */
  543.     UWB_NOTIF_BG_LEAVE = 1,    /* radio controller left a beacon group */
  544.     UWB_NOTIF_ONAIR,
  545.     UWB_NOTIF_OFFAIR,
  546. };
  547.  
  548. /* Callback function registered with UWB */
  549. struct uwb_notifs_handler {
  550.     struct list_head list_node;
  551.     void (*cb)(void *, struct uwb_dev *, enum uwb_notifs);
  552.     void *data;
  553. };
  554.  
  555. int uwb_notifs_register(struct uwb_rc *, struct uwb_notifs_handler *);
  556. int uwb_notifs_deregister(struct uwb_rc *, struct uwb_notifs_handler *);
  557.  
  558.  
  559. /**
  560.  * UWB radio controller Event Size Entry (for creating entry tables)
  561.  *
  562.  * WUSB and WHCI define events and notifications, and they might have
  563.  * fixed or variable size.
  564.  *
  565.  * Each event/notification has a size which is not necessarily known
  566.  * in advance based on the event code. As well, vendor specific
  567.  * events/notifications will have a size impossible to determine
  568.  * unless we know about the device's specific details.
  569.  *
  570.  * It was way too smart of the spec writers not to think that it would
  571.  * be impossible for a generic driver to skip over vendor specific
  572.  * events/notifications if there are no LENGTH fields in the HEADER of
  573.  * each message...the transaction size cannot be counted on as the
  574.  * spec does not forbid to pack more than one event in a single
  575.  * transaction.
  576.  *
  577.  * Thus, we guess sizes with tables (or for events, when you know the
  578.  * size ahead of time you can use uwb_rc_neh_extra_size*()). We
  579.  * register tables with the known events and their sizes, and then we
  580.  * traverse those tables. For those with variable length, we provide a
  581.  * way to lookup the size inside the event/notification's
  582.  * payload. This allows device-specific event size tables to be
  583.  * registered.
  584.  *
  585.  * @size:   Size of the payload
  586.  *
  587.  * @offset: if != 0, at offset @offset-1 starts a field with a length
  588.  *          that has to be added to @size. The format of the field is
  589.  *          given by @type.
  590.  *
  591.  * @type:   Type and length of the offset field. Most common is LE 16
  592.  *          bits (that's why that is zero); others are there mostly to
  593.  *          cover for bugs and weirdos.
  594.  */
  595. struct uwb_est_entry {
  596.     size_t size;
  597.     unsigned offset;
  598.     enum { UWB_EST_16 = 0, UWB_EST_8 = 1 } type;
  599. };
  600.  
  601. int uwb_est_register(u8 type, u8 code_high, u16 vendor, u16 product,
  602.              const struct uwb_est_entry *, size_t entries);
  603. int uwb_est_unregister(u8 type, u8 code_high, u16 vendor, u16 product,
  604.                const struct uwb_est_entry *, size_t entries);
  605. ssize_t uwb_est_find_size(struct uwb_rc *rc, const struct uwb_rceb *rceb,
  606.               size_t len);
  607.  
  608. /* -- Misc */
  609.  
  610. enum {
  611.     EDC_MAX_ERRORS = 10,
  612.     EDC_ERROR_TIMEFRAME = HZ,
  613. };
  614.  
  615. /* error density counter */
  616. struct edc {
  617.     unsigned long timestart;
  618.     u16 errorcount;
  619. };
  620.  
  621. static inline
  622. void edc_init(struct edc *edc)
  623. {
  624.     edc->timestart = jiffies;
  625. }
  626.  
  627. /* Called when an error occured.
  628.  * This is way to determine if the number of acceptable errors per time
  629.  * period has been exceeded. It is not accurate as there are cases in which
  630.  * this scheme will not work, for example if there are periodic occurences
  631.  * of errors that straddle updates to the start time. This scheme is
  632.  * sufficient for our usage.
  633.  *
  634.  * @returns 1 if maximum acceptable errors per timeframe has been exceeded.
  635.  */
  636. static inline int edc_inc(struct edc *err_hist, u16 max_err, u16 timeframe)
  637. {
  638.     unsigned long now;
  639.  
  640.     now = jiffies;
  641.     if (now - err_hist->timestart > timeframe) {
  642.         err_hist->errorcount = 1;
  643.         err_hist->timestart = now;
  644.     } else if (++err_hist->errorcount > max_err) {
  645.             err_hist->errorcount = 0;
  646.             err_hist->timestart = now;
  647.             return 1;
  648.     }
  649.     return 0;
  650. }
  651.  
  652.  
  653. /* Information Element handling */
  654.  
  655. /* For representing the state of writing to a buffer when iterating */
  656. struct uwb_buf_ctx {
  657.     char *buf;
  658.     size_t bytes, size;
  659. };
  660.  
  661. typedef int (*uwb_ie_f)(struct uwb_dev *, const struct uwb_ie_hdr *,
  662.             size_t, void *);
  663. struct uwb_ie_hdr *uwb_ie_next(void **ptr, size_t *len);
  664. ssize_t uwb_ie_for_each(struct uwb_dev *uwb_dev, uwb_ie_f fn, void *data,
  665.             const void *buf, size_t size);
  666. int uwb_ie_dump_hex(struct uwb_dev *, const struct uwb_ie_hdr *,
  667.             size_t, void *);
  668. int uwb_rc_set_ie(struct uwb_rc *, struct uwb_rc_cmd_set_ie *);
  669. struct uwb_ie_hdr *uwb_ie_next(void **ptr, size_t *len);
  670.  
  671.  
  672. /*
  673.  * Transmission statistics
  674.  *
  675.  * UWB uses LQI and RSSI (one byte values) for reporting radio signal
  676.  * strength and line quality indication. We do quick and dirty
  677.  * averages of those. They are signed values, btw.
  678.  *
  679.  * For 8 bit quantities, we keep the min, the max, an accumulator
  680.  * (@sigma) and a # of samples. When @samples gets to 255, we compute
  681.  * the average (@sigma / @samples), place it in @sigma and reset
  682.  * @samples to 1 (so we use it as the first sample).
  683.  *
  684.  * Now, statistically speaking, probably I am kicking the kidneys of
  685.  * some books I have in my shelves collecting dust, but I just want to
  686.  * get an approx, not the Nobel.
  687.  *
  688.  * LOCKING: there is no locking per se, but we try to keep a lockless
  689.  * schema. Only _add_samples() modifies the values--as long as you
  690.  * have other locking on top that makes sure that no two calls of
  691.  * _add_sample() happen at the same time, then we are fine. Now, for
  692.  * resetting the values we just set @samples to 0 and that makes the
  693.  * next _add_sample() to start with defaults. Reading the values in
  694.  * _show() currently can race, so you need to make sure the calls are
  695.  * under the same lock that protects calls to _add_sample(). FIXME:
  696.  * currently unlocked (It is not ultraprecise but does the trick. Bite
  697.  * me).
  698.  */
  699. struct stats {
  700.     s8 min, max;
  701.     s16 sigma;
  702.     atomic_t samples;
  703. };
  704.  
  705. static inline
  706. void stats_init(struct stats *stats)
  707. {
  708.     atomic_set(&stats->samples, 0);
  709.     wmb();
  710. }
  711.  
  712. static inline
  713. void stats_add_sample(struct stats *stats, s8 sample)
  714. {
  715.     s8 min, max;
  716.     s16 sigma;
  717.     unsigned samples = atomic_read(&stats->samples);
  718.     if (samples == 0) {    /* it was zero before, so we initialize */
  719.         min = 127;
  720.         max = -128;
  721.         sigma = 0;
  722.     } else {
  723.         min = stats->min;
  724.         max = stats->max;
  725.         sigma = stats->sigma;
  726.     }
  727.  
  728.     if (sample < min)    /* compute new values */
  729.         min = sample;
  730.     else if (sample > max)
  731.         max = sample;
  732.     sigma += sample;
  733.  
  734.     stats->min = min;    /* commit */
  735.     stats->max = max;
  736.     stats->sigma = sigma;
  737.     if (atomic_add_return(1, &stats->samples) > 255) {
  738.         /* wrapped around! reset */
  739.         stats->sigma = sigma / 256;
  740.         atomic_set(&stats->samples, 1);
  741.     }
  742. }
  743.  
  744. static inline ssize_t stats_show(struct stats *stats, char *buf)
  745. {
  746.     int min, max, avg;
  747.     int samples = atomic_read(&stats->samples);
  748.     if (samples == 0)
  749.         min = max = avg = 0;
  750.     else {
  751.         min = stats->min;
  752.         max = stats->max;
  753.         avg = stats->sigma / samples;
  754.     }
  755.     return scnprintf(buf, PAGE_SIZE, "%d %d %d\n", min, max, avg);
  756. }
  757.  
  758. static inline ssize_t stats_store(struct stats *stats, const char *buf,
  759.                   size_t size)
  760. {
  761.     stats_init(stats);
  762.     return size;
  763. }
  764.  
  765. #endif /* #ifndef __LINUX__UWB_H__ */
  766.